---
type: engineering-note
title: Docs-First Implementation
description: Spec, build and close the loop through the knowledge base — feature rows are the spec, evidence is the definition of done.
tags: [engineering, skill]
timestamp: {{DATE}}
---
<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->
# Docs-First Implementation

_Adapted for this knowledge base from
[Matt Pocock's engineering skills](https://github.com/mattpocock/skills/tree/main/skills/engineering)
(to-spec · to-tickets · implement)._

## When to use
Any non-trivial piece of work, by human or coding agent.

## The loop
1. **Spec = rows.** Before building, the work must exist as `## Features`
   rows (for pages/modules/services) or `## Scenarios` rows (for flows) —
   one row per acceptance criterion, `f<n>`/`s<n>` ids. No prose specs that
   can't be checked off.
2. **Doubts before code.** Anything underspecified becomes an open question
   with `About` pointing at the blocked row. An agent that guesses instead of
   asking has failed the loop — the `unspecified` derived state exists to
   make waiting-on-answers visible.
3. **Build, then cite.** Implementation fills the `Implemented` cell with
   *how* it works plus evidence URIs (`repo:// route:// api:// db://`).
   A row without evidence claims nothing.
4. **Prove, then close.** Add the `test://` URI. The row derives `built`;
   the dashboard's untested counters are the remaining backlog.
5. **Same PR.** Docs and code change together — a diff that changes behaviour
   without touching its rows is incomplete by definition.

## Definition of done
`dj lint` clean · the row derives `built` (or `covered`) · no open
question left pointing at it.

## Open questions